.\" This is a Unix manpage. png2ico.txt contains the same text suitable for
.\" reading in Windows (with Notepad, Wordpad, Word,...).
.\" 
.\" Copyright (C) 2003 Matthias S. Benkmann <m.s.b@gmx.net>
.\"
.TH png2ico 1 "9 January 2003"

.SH NAME
png2ico \- convert .PNG file(s) to Windows .ICO icon resource

.SH SYNOPSIS
.B png2ico 
outfile.ico [--colors <num>] infile1.png [infile2.png ...]

.SH DESCRIPTION
\fBpng2ico\fP takes the input files and stores them in the output file
as a Windows icon resource. Usually the input files would all represent the
same image in different resolutions (common resolutions are 16x16, 32x32
and 64x64). A program reading the icon resource will pick the image
closest to its desired resolution and will then scale it if necessary.

Using the parameter \fI--colors\fP you can specify the number of colors
to use for the images that follow \fI--colors\fP on the command line.
Allowed values are
2, 16 and 256. If omitted, 256 colors will be used. \fI--colors\fP can be
specified multiple times to store images with different numbers of colors
in the same icon file. If the source image has more than the specified
number of colors, color reduction will be performed.

.SH "FAVICON.ICO"
Most graphical browsers today support the \fIfavicon.ico\fP file. When
a user bookmarks a web page, the browser will automatically check if it finds
a \fIfavicon.ico\fP file on the web server and display it in the bookmarks menu.
Depending on the browser and configuration the \fIfavicon.ico\fP may also
appear in other places. 

To create a \fIfavicon.ico\fP simply create a 
16x16 .PNG file and convert it to an icon resource with 
\fBpng2ico\fP. You may of course add other alternative resolutions but most
browsers only use a 16x16 image. Keep in mind that for a user with a slow
modem a \fIfavicon.ico\fP may increase the page loading time by a few seconds
if it is too large, so don't overdo it. Adding a 32x32 alternative
should be enough to make sure the image will look good even in contexts with
larger icons. Adding even more and larger alternatives is unnecessary bloat.
Try to keep the number of colors below 16 and create a 16-color icon using
the \fI--colors 16\fP switch of \fBpng2ico\fP (or even create a b/w icon
using the \fI--colors 2\fP switch). This will result in a smaller
file that loads faster.

Don't forget that the \fIfavicon.ico\fP may be composed against backgrounds of
different colors so you should use transparency rather than a solid background 
if you want to avoid that your icon appears inside a box.

To add your new \fIfavicon.ico\fP to a web page put it on the server into
the same directory as the web page. That is the 1st place a browser will look.
If it doesn't find an icon there, it checks the top-level directory of the
web server, so by putting it there you can have a default favicon for all
the pages in your domain.
Depending on browser and configuration, the \fIfavicon.ico\fP is not always
rendered, even if it is in one of the above locations, unless the web page 
explicitly declares its presence. To declare that your web page has an icon,
you add the following 2 lines into the \fB<head>\fP section of your page:

.RS
.B <link rel="icon" href="favicon.ico" type="image/x\-icon">

.B <link rel="shortcut\ icon" href="favicon.ico" type="image/x\-icon">
.RE

.SH EXAMPLES

To create a favicon.ico from 2 logo files (the 1st in 16x16 resolution and
the 2nd in 32x32 resolution) you could use the following command:

.RS
.B png2ico favicon.ico logo16x16.png logo32x32.png
.RE

.SH BUGS
The color reduction algorithm used by \fBpng2ico\fP is very slow. If you
have an input file with several thousand colors (very unlikely), it may take
several seconds to create the icon. If possible, reduce the number of colors
in your .PNG files before passing them to \fBpng2ico\fP.

The handling of the transparency mask is very inconsistent in programs.
The same program will sometimes interpret it differently depending on context.
\fBpng2ico\fP takes precautions to make sure that the icon will always
look the same. For doing this, \fBpng2ico\fP
uses one palette entry for black (0,0,0) and one 
palette entry for white (255,255,255), even if the icon does not have a single
black or white pixel. This means that 2-color icons will always be black
and white. In 16/256-color icons, only 14/254 colors can be chosen freely.

.SH AUTHOR
Matthias S. Benkmann <matthias@winterdrache.de>.

\fBpng2ico\fP lives at http://www.winterdrache.de/freeware

.SH "SEE ALSO"
.BR convert(1), 
.BR gimp(1)
